Loadstar 248/248.d81/t.db+ doc 3

Text File | 2022-08-26 | 14KB | 542 lines

u
            DOTBASIC PLUS
               Part III
     by Dave Moorman & Lee Novak


    Never again must you fight for
string space in your text adventures
and other programs. With the following
commands, you can put your lines of
text in a Edstar file (Edstar is our
nifty text editor that produces 38-
column lines of text), use .BL0 to
bload it into memory (under ROM), the
use RACK (.RK) to turn the text into a
virtual string array. RACK INDEX (.RI)
will put any line into W$ for use in
your program. Here is a simple
example:

 100 .BL0,"T.DISKOVER",D,40960
 110 .RK,40960
 120 FOR X = 1 TO N%
 130 .RI,X
 140 PRINT W$
 150 NEXT


  RACK EDSTAR FILE
  ----------------
    Include: .RK
  .RK,LOCATION

    This routine takes an EDSTAR file
(terminated by a zero) and "racks it
up". A table of pointers is created
right after the zero at the end of the
text, enabling you to use .RI or .PRI
to grab or print individual lines of
the file.

    The file can be located anywhere
in memory, even under I/O. Racking
needs 3 bytes per line at the end of
the file for its pointers. The total
number of items is returned in N%.


  INDEX ITEM
  ----------
    Include: .RI
  .RI,INDEX#

    Once you've racked up an EDSTAR
file, you can index it. The indexed
item is returned in W$. F$ is also set
by indexing, and will always return a
null unless you happen to be looking
at a directory, in which case it
contains the entry's filename.


  PRINT ITEM
  ----------
    Include: .PRI
  .PRI,X,Y,INDEX#

    This routine indexes an item and
prints it anywhere on the screen. The
string is NOT returned in W$ or F$.


  PRINT FILENAME
  ----------
    Include: .PRFILE
  .PRFILE,X,Y,INDEX#

    If you've used GET DIRECTORY and
have racked up the resulting text, you
can immediately print the filenames.


  DEFINE REGION TEXT
  ------------------
    Include: .DRTEXT
  .DRTEXT,NUMBER,"STATIC STRING"

    The concept of "region text" for
LOADSTAR programs is credited to both
Jeff Jones and myself. CASH FLOWER (LS
#161) and QUICKSMITH (LS #164) both
used the concept, and it's interesting
to note that neither of us knew what
the other was up to.

    "Region text" is when the user
moves the mouse pointer around the
screen, and a message bar at the
bottom of the screen informs the user
of what will happen if he or she
clicks on that particular area. These
strings don't have to be associated
with regions - it's just likely that
this will be their most common use.

   Related Variables:     (& defaults)

  MV+20  Region Text Zone (LB)     (0)
  MV+21  Region Text Zone (HB)     (4)
  MV+22  Region Text Color / Flags (1)
  MV+23  Region Text Row          (24)

    Strings defined as region text
must NOT be made by combining smaller
strings. The string's POINTER will be
stored in its proper slot in the
Region Text Zone. Be sure this zone is
safe from BASIC and other data We
suggest the area in pages 46-55. The
Zone will never exceed 3 pages.

    All region text will be printed in
MV+22's color. Add 128 to MV+22 for
REVERSE printing. (Adding 64 changes
the way the pointers are stored and is
most useful from ML.)

    Add 32 to MV+22 and all your
region text will be CENTERED. Add 16
instead, and each string will be
printed after a forced leading SPACE.


  EDSTAR TO REGION TEXT
  ---------------------
    Include: .EDRTEXT
  .EDRTEXT,LOCATION

    This command defines ALL region
text with a single command! It takes
an EDSTAR file (terminated by 0),
racks it up, and POKEs MV+24 and
MV+25. The number of lines in the file
is returned in N%.

    Keep in mind that the FIRST line
of the EDSTAR file will be referenced
by number zero. You can have as many
lines as you want.


  PRINT REGION TEXT
  -----------------
    Include: .PRTEXT
  .PRTEXT,INDEX

    This prints region text on the
line specified in MV+23. It fills up
the unused part of the line with
spaces, so you don't have to worry
about erasing the old text before
printing over it. The string will be
printed as specified in MV+22, above.
Usually the "index" will be RG%, but
it doesn't have to be.

    Here is a simple example:

 100 .BL0,"TEXTFILE",D,40960
 110 .EDRTEXT,40960
 200 .DO:.MA
 210 .PRTEXT,RG%
 220 .UN CR%


  PRINT MESSAGE
  -------------
    Include: .MSG
  .MSG,COLOR,STRING

    This command prints your string
just like region text. You provide the
color, and MV+22 specifies the reverse
state, centering, or the leading
space. This command is useful for
special prompts and messages. The plus
"+" can be used to concatenate strings
printed by this routine.


  GET DIRECTORY
  -------------
    Include: .DIR
  .DIR,"$:*",D,LOC,#FILENAMES

    This will read the disk directory
from device D. The directory can be
placed anywhere, even under I/O. DB+
converts the directory to an EDSTAR
file as it is brought in. This allows
SCROLLING MENU to use the information
as a file requestor.

    Normally you would use "$:*" to
get all the disk's filenames. You can
replace "$:*" with any search pattern
you want, up to 16 characters long.
For example, using "$:b.*,p.*" on a
LOADSTAR disk (using a real C-64 or
True Drive in VICE) would bring in the
names of all the boot and text files.

    E$ will return the error message.
T$ will contain the disk's name within
quotes, and B$ will contain the
"blocks free" message. Use VAL(B$) to
extract the number of blocks free on
the disk. N% returns the number of
filenames loaded.

    If there was an error during the
directory getting, T$ and B$ will
return strings full of spaces, and E$
will tell about the error. The one
thing your program should do before
disk access is check if the drive is
actually online, like this:

   1000 close2:open2,dv,2:close2
   1010 if st=-128 then...
   1020 ...continue

    Line 1010 would go and deal with a
"device not present" situation. If all
is well, line 1020 executes and disk
access occurs.

    GET DIRECTORY has been greatly
improved with the addition of one more
parameter: how many filenames you have
room to hold. This number should be
calculated as:

   # files = INT((bufferspace-1)/32)

     For example, if your buffer was
from 49152 to 53248, you could fit
INT((4096-1)/32) = 127 names there.
This formula takes into account the
zero cap and the three bytes per line
that the racking process needs.

    If the buffer space is filled up
before all the filenames are loaded,
B$ will return "more files on disk".
If you don't care about buffer space,
use 0 for the number of filenames.

    A good place to put your directory
information is in pages 224+. You
easily put 250 filenames in this area
under ROM.


  SCROLLING MENU
  --------------
    Include: .SCMENU
  .SCMENU,X,Y,W,H,B,I,UN,HI,LOC,T$,B$

    For this command to work, you must
have an EDSTAR file in memory, and it
must end with a zero byte OR use .DIR
to get the directory.

    The X,Y,W,H parameters set the
area the menu will occupy. H must be
at least 7 characters tall and W 11
wide. B is the color of the menu box.
The unhighlighted items of the menu
are color UN. HI is the highlight bar
color. If you don't want the text to
reverse or un-reverse as the bar
moves, add 128 to HI.

    I is the color of the four words
in the corners of the menu: HOME, UP,
DOWN, and QUIT. Left-click on UP or
DOWN to scroll the text. Right-click
on them and the list jumps a page at a
time. The user can use the CRSR keys
to scroll or page through the text as
well.

    Clicking on HOME will bring the
list to the top. Pressing the HOME key
will bring the highlight bar to the
top of the page, and the next press
brings the list to the top.

    Click on an item or press RETURN
to select it. The entire item is
returned in W$. F$ will return a null
unless this is a file requestor - in
which case it contains the filename.
SL% returns the selection number.

    Clicking on QUIT, pressing Q, or
pressing the Global Escape key will
return zero in SL% and nulls in W$ and
F$.

    LOC is the location of the EDSTAR
file, which can be anywhere in memory.
The file will be "racked up" before
use, which can take up to a second
(gasp!) on 1 MHz machines. For already
racked data, put 0 in LOC.

    T$ is printed at the menu's top,
in r